joke.enterprises

work in progress

08/11/2026 - Code is just Linguistics

Short one this time! Writing this on a train from home from a fantastic trip I had to see my lovely friend Penn(y) and to meet the other members of the Underground Transgender Mafia

One thing that continually manages to get on my nerves about how programming is taught and generally styled (especially in the age of LLM-based programming, though I have yet to largely succumb to this) is how people continually do not manage to *get* the purpose of a comment, or really why we write code in general, I think it's very easy to fall into the trap of writing code purely to tell a computer what to do, which is obviously why we learn to program in the first place, so it makes sense, but it's really not right at all.

Generally, as actual serious software developers, we expect our code to be read by people that are not us, I would argue that The Point of code is largely to be read by other people, it's generally not actually that hard to figure out roughly how to tell a computer what to do, but as programmers we are also continually explaining what our dcode does to other programmers, or even non-programmers. If you've ever worked in software dev professionally you've definitely had the experience of tracking down some inane commit made 5 years ago, only to check the blame and find out the guy who wrote it retired last year.

So, in this scenario, what would've made the programmer being gone less eggregious? More readable code! duh! If the code in question was easier to understand, maybe you wouldn't even need to check the commit history on it! The issue here is that it's not immediately obvious what the theoretical code was *trying* to do, so if it doesn't work, you can't quite tell what you even need to fix, what the intentions are behind it. etc etc.

How do we fix this then? Well, if we need to make our intentions clear, why not just leave a comment? Isn't that the point of those! Oh my god no please try not to do this

I think generally it's easy to think of code as "harder to understand" than English, so if we want to describe how something works, we should write a comment. On the extreme end, this often leads to people writing comments to describe exactly what each block of code does, before the code, this largely makes it all much harder to understand, though. Imagine working in a kitchen, and every time someone screams out a ticket for the next order coming up, they come up to you, pat you on the back and calmly tell you in detailed prose the people that make up the table that ordered the dish, and the tastes that led them to order what they did. This is largely what you're doing when you do this!

I think as programmers, we need to keep in mind that any code we write is simultaneously being written for computers, that read code to emit assembly, which they process, and programmers, that read code to emit Human Thoughts, which they process. We're really not too different and as programmers we're trained to be able to read and process code extremely quickly, so we understand what we're looking at. So in that case, we can really think of code as a language, possibly a dialect of English, that can be read by both computers and trained humans! Wherever possible, we should try to keep our explanation of how our code works in code, through keeping our code more structured and readable (similarly to how an overly long, run-on sentence is hard to digest for English readers) and by using verbose and descriptive variable and method names, if you're actually wwriting code well this makes it reasonably easy to write code that just Makes Sense, and if it doesn't, then you can clarify with a comment! Just be careful with them!

Documentation also sucks for this kind of, it's quite common to see people write a doc comment above each function definition detailing a function's purpose and output. This is dumb because method signatures already do this if you're writing good code. This is partially why I really quite like C's header/source file model, because header files just give you a list of all the function definitions in a file.

Also lowkey per-method doc comments don't even really help most of the time because like, again it's easy to tell what a function does from its signature. I think the best reason to have documentation is to describe a system at a high level, or to prime someone with key concepts for dense files. This is like teaching someone the right vocab to understand a more complex text that uses uncommon language, or assumes knowledge of a culture they're not familiar with. It makes it much easier to understand what each individual block of code is actually doing, which is much more helpful than just telling someone what some one-line method does in English, which they could probably already figure out!

I think these concepts can also largely be applied to how we structure code, think about like, why you bother making a "magic number" a constant, does it make sense to define some constant at the top of a file? maybe you can bring that definition a little closer to where it's used, so you can understand it more locally to the code you're writing? or maybe sometimes SetHealth( player, 100 ) is just self-explanatory if you wanna set a player's health to 100. it's not exactly hard to tweak that 100, either, so you're probably not making it more """maintainable""" by moving it out. Just try to think of your code as something that should flow like an English text, i think.

see blog for many more new posts!